<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  <link rel="stylesheet" href="docgen-resources/docgen.css" type="text/css">
  <meta name="generator" content="FreeMarker Docgen (DocBook 5)">
  <title>
    FreeMarker Manual - Error handling
  </title>
    <script type="text/javascript" src="docgen-resources/jquery.js"></script>
    <script type="text/javascript" src="docgen-resources/linktargetmarker.js"></script>
</head>
<body>

    <div class="navigation">
    <div class="breadcrumb">
<span class="breadcrumb">        You are here:
          <a href="index.html">Book</a>
            <b>></b>
          <a href="pgui.html">Programmer's Guide</a>
            <b>></b>
          <a href="pgui_config.html">The Configuration</a>
            <b>></b>
          Error handling
</span>    </div>
    <div class="bookmarks">
<span class="bookmarks">Bookmarks:
<a href="alphaidx.html">Alphabetical Index</a>, <a href="gloss.html">Glossary</a>, <a href="ref.html">Reference</a>, <a href="app_faq.html">FAQ</a>, <a href="api/index.html">Java API</a>, <a href="../index.html">FreeMarker Home</a></span>    </div>
    <div class="pagers">
      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
<div class="pagerButton"><a href="pgui_misc.html"><span class="hideA">Next page: </span>Miscellaneous</a></div><div class="pagerButton"><a href="pgui_config_templateloading.html">Previous page</a></div><div class="pagerButton"><a href="pgui_config.html">Parent page</a></div><div class="pagerButton"><a href="index.html">Contents</a></div>      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
    </div>
    </div>

<div id="mainContent">

  
  
  
  
  <h1 class="rank_section1"
        id="pageTopTitle">
<a name="pgui_config_errorhandling"></a>Error handling  </h1>
    
    <div class="toc">
      <p>
        <b>
            Page Contents
        </b>
      </p>
      
  <ul class="noMargin">
      <li>
        <a href="#autoid_43">The possible exceptions</a>
      </li>
      <li>
        <a href="#autoid_44">Customizing the behavior regarding TemplatException-s</a>
      </li>
      <li>
        <a href="#autoid_45">Explicit error handling in templates</a>
      </li>
  </ul>
    </div>
    <a name="docgen_afterTheTOC"></a>
    

            
  
  
  
  <h2 class="rank_section2"
        >
<a name="autoid_43"></a>The possible exceptions  </h2>


          <p>The exceptions that can occur regarding FreeMarker could be
          classified like this:</p>

              <div class="itemizedlist">
<ul>
            <li>
              <p>Exceptions occurring when you configure FreeMarker:
              Typically you configure FreeMarker only once in your
              application, when your application initializes itself. Of
              course, during this, exceptions can occur, as it is obvious from
              the FreeMarker API...</p>
            </li>

            <li>
              <p>Exceptions occurring when loading and parsing templates:
              When you call
              <tt style="color: #A03D10">Configuration.getTemplate(<i style="color: #DD4400">...</i>)</tt>,
              FreeMarker has to load the template file into the memory and
              parse it (unless the template is already <a href="pgui_config_templateloading.html#pgui_config_templateloading_caching">cached</a> in
              that <tt style="color: #A03D10">Configuration</tt> object). During this, two
              kind of exceptions can occur:</p>

                  <div class="itemizedlist">
<ul>
                <li>
                  <p><tt style="color: #A03D10">IOException</tt> because the template
                  file was not found, or other I/O problem occurred while
                  trying to read it, for example you have no right to read the
                  file, or there are disk errors. The emitter of these errors
                  is the <a href="pgui_config_templateloading.html"><tt>TemplateLoader</tt>
                  object</a>, which is plugged into the
                  <tt style="color: #A03D10">Configuration</tt> object. (For the sake of
                  correctness: When I say ``file'' here, that's a
                  simplification. For example, templates can be stored in a
                  table of a relational database as well. This is the business
                  of the <tt style="color: #A03D10">TemplateLoader</tt>.)</p>
                </li>

                <li>
                  <p><tt style="color: #A03D10">freemarker.core.ParseException</tt>
                  because the template file is syntactically incorrect
                  according the rules of the FTL language. The point is that
                  this error occurs when you obtain the
                  <tt style="color: #A03D10">Template</tt> object
                  (<tt style="color: #A03D10">Configuration.getTemplate(<i style="color: #DD4400">...</i>)</tt>),
                  and not when you execute
                  (<tt style="color: #A03D10">Template.process(<i style="color: #DD4400">...</i>)</tt>)
                  the template. This exception is an
                  <tt style="color: #A03D10">IOException</tt> subclass.</p>
                </li>
              </ul>    </div>

            </li>

            <li>
              <p>Exceptions occurring when executing (processing)
              templates, that is, when you call
              <tt style="color: #A03D10">Template.process(<i style="color: #DD4400">...</i>)</tt>.
              Two kind of exceptions can occur:</p>

                  <div class="itemizedlist">
<ul>
                <li>
                  <p><tt style="color: #A03D10">IOException</tt> because there was an
                  error when trying to write into the output writer.</p>
                </li>

                <li>
                  <p><tt style="color: #A03D10">freemarker.template.TemplatException</tt>
                  because other problem occurred while executing the template.
                  For example, a frequent error is when a template refers to a
                  variable which is not existing. Be default, when a
                  <tt style="color: #A03D10">TemplatException</tt> occurs, FreeMarker
                  prints the FTL error message and the stack trace to the
                  output writer with plain text format, and then aborts the
                  template execution by re-throwing the
                  <tt style="color: #A03D10">TemplatException</tt>, which then you can
                  catch as
                  <tt style="color: #A03D10">Template.process(<i style="color: #DD4400">...</i>)</tt>
                  throws it. But this behavior can be customized. FreeMarker
                  always <a href="pgui_misc_logging.html">logs</a>
                  <tt style="color: #A03D10">TemplatException</tt>-s.</p>
                </li>
              </ul>    </div>

            </li>
          </ul>    </div>

        
            
  
  
  
  <h2 class="rank_section2"
        >
<a name="autoid_44"></a>Customizing the behavior regarding TemplatException-s  </h2>


          <p><tt style="color: #A03D10">TemplateException</tt>-s thrown during the
          template processing are handled by the
          <tt style="color: #A03D10">freemarker.template.TemplateExceptionHandler</tt>
          object, which is plugged into the <tt style="color: #A03D10">Configuration</tt>
          object with its
          <tt style="color: #A03D10">setTemplateExceptionHandler(<i style="color: #DD4400">...</i>)</tt>
          mehod. The <tt style="color: #A03D10">TemplateExceptionHandler</tt> contains 1
          method:</p>

          <div align="left" class="programlisting"><table bgcolor="#F8F8F8" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#F8F8F8" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
void handleTemplateException(TemplateException te, Environment env, Writer out) 
        throws TemplateException;&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


          <p>Whenever a <tt style="color: #A03D10">TemplateException</tt> occurs, this
          method will be called. The exception to handle is passed with the
          <tt style="color: #A03D10">te</tt> argument, the runtime environment of the
          template processing is accessible with the <tt style="color: #A03D10">env</tt>
          argument, and the handler can print to the output using the
          <tt style="color: #A03D10">out</tt> argument. If the method throws exception
          (usually it re-throws <tt style="color: #A03D10">te</tt>), then the template
          processing will be aborted, and
          <tt style="color: #A03D10">Template.process(<i style="color: #DD4400">...</i>)</tt>
          will throw the same exception. If
          <tt style="color: #A03D10">handleTemplateException</tt> doesn't throw exception,
          then template processing continues as if nothing had happen, but the
          statement that caused the exception will be skipped (see more
          later). Of course, the handler can still print an error indicator to
          the output.</p>

          <p>In any case, before the
          <tt style="color: #A03D10">TemplateExceptionHandler</tt> is invoked, FreeMarker
          will <a href="pgui_misc_logging.html">log</a> the
          exception.</p>

          <p>Let's see how FreeMarker skips ``statements'' when the error
          handler doesn't throw exception, through examples. Assume we are
          using this template exception handler:</p>

          <div align="left" class="programlisting"><table bgcolor="#F8F8F8" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#F8F8F8" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
class MyTemplateExceptionHandler implements TemplateExceptionHandler {
    public void handleTemplateException(TemplateException te, Environment env, java.io.Writer out)
            throws TemplateException {
        try {
            out.write(&quot;[ERROR: &quot; + te.getMessage() + &quot;]&quot;);
        } catch (IOException e) {
            throw new TemplateException(&quot;Failed to print error message. Cause: &quot; + e, env);
        }
    }
}

<i>...</i>

cfg.setTemplateExceptionHandler(new MyTemplateExceptionHandler());&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


          <p>If an error occurs in an interpolation which is not inside an
          FTL tag (that is, not enclosed into
          <tt style="color: #A03D10">&lt;#<i style="color: #DD4400">...</i>&gt;</tt> or
          <tt style="color: #A03D10">&lt;@<i style="color: #DD4400">...</i>&gt;</tt>), then
          the whole interpolation will be skipped. So this template (assuming
          that <tt style="color: #A03D10">badVar</tt> is missing from the
          data-model):</p>

          <div align="left" class="programlisting"><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
a${badVar}b&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


          <p>will print this if we use the
          <tt style="color: #A03D10">MyTemplateExceptionHandler</tt>:</p>

          <div align="left" class="programlisting"><table bgcolor="#CCFFCC" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#CCFFCC" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
a[ERROR: Expression badVar is undefined on line 1, column 4 in test.ftl.]b&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


          <p>This template will print the same (except that the column
          number will differ...):</p>

          <div align="left" class="programlisting"><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
a${&quot;moo&quot; + badVar}b&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


          <p>since, as it was written, the whole interpolation is skipped
          if any error occurs inside it.</p>

          <p>If an error occurs when evaluating the value of a parameter
          for a directive call, or if there are other problems with the
          parameter list, or if an error occurs when evaluating
          <tt style="color: #A03D10"><i style="color: #DD4400">exp</i></tt> in
          <tt style="color: #A03D10">&lt;@<i style="color: #DD4400">exp</i>
          <i style="color: #DD4400">...</i>&gt;</tt>, or if the value of
          <tt style="color: #A03D10"><i style="color: #DD4400">exp</i></tt> is not an
          user-defined directive, then the whole directive call is skipped.
          For example this:</p>

          <div align="left" class="programlisting"><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
a&lt;#if badVar&gt;Foo&lt;/#if&gt;b&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


          <p>will print this:</p>

          <div align="left" class="programlisting"><table bgcolor="#CCFFCC" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#CCFFCC" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
a[ERROR: Expression badVar is undefined on line 1, column 7 in test.ftl.]b&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


          <p>Note that the error occurred in the <tt style="color: #A03D10">if</tt>
          start-tag (<tt style="color: #A03D10">&lt;#if badVar&gt;</tt>), but the whole
          directive call was skipped. Logically, the nested content
          (<tt style="color: #A03D10">Foo</tt>) was skipped with this, since the nested
          content is handled (printed) by the enclosing directive
          (<tt style="color: #A03D10">if</tt>).</p>

          <p>The output will be the same with this (except that the column
          number will differ...):</p>

          <div align="left" class="programlisting"><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
a&lt;#if &quot;foo${badVar}&quot; == &quot;foobar&quot;&gt;Foo&lt;/#if&gt;b&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


          <p>since, as it was written, the whole directive calling will be
          skipped if any error occurs during the parameter evaluation.</p>

          <p>The directive call will not be skipped if the error occurs
          after the execution of the directive was already started. That is,
          if an error occurs in the nested content:</p>

          <div align="left" class="programlisting"><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
a
&lt;#if true&gt;
  Foo
  ${badVar}
  Bar
&lt;/#if&gt;
c&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


          <p>or in the macro definition body:</p>

          <div align="left" class="programlisting"><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
a
&lt;@test /&gt;
b
&lt;#macro test&gt;
  Foo
  ${badVar}
  Bar
&lt;/#macro&gt;&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


          <p>the output will be something like:</p>

          <div align="left" class="programlisting"><table bgcolor="#CCFFCC" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#CCFFCC" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
a
  Foo
  [ERROR: Expression badVar is undefined on line 4, column 5 in test.ftl.]
  Bar
c&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


          <p>FreeMarker comes with these prewritten error handlers:</p>

              <div class="itemizedlist">
<ul>
            <li>
              <p><tt style="color: #A03D10">TemplateExceptionHandler.DEBUG_HANDLER</tt>:
              Prints stack trace (includes FTL error message and FTL stack
              trace) and re-throws the exception. This is the default handler
              (that is, it is initially prugged into all new
              <tt style="color: #A03D10">Configuration</tt> objects).</p>
            </li>

            <li>
              <p><tt style="color: #A03D10">TemplateExceptionHandler.HTML_DEBUG_HANDLER</tt>:
              Same as <tt style="color: #A03D10">DEBUG_HANDLER</tt>, but it formats the
              stack trace so that it will be readable with Web browsers.
              Recommended over <tt style="color: #A03D10">DEBUG_HANDLER</tt> when you
              generate HTML pages.</p>
            </li>

            <li>
              <p><tt style="color: #A03D10">TemplateExceptionHandler.IGNORE_HANDLER</tt>:
              Simply suppresses all exceptions (but remember, FreeMarker will
              still log them). It does nothing to handle the event. It does
              not re-throw the exception.</p>
            </li>

            <li>
              <p><tt style="color: #A03D10">TemplateExceptionHandler.RETHROW_HANDLER</tt>:
              Simply re-throws all exceptions, it doesn't do anything else.
              This handler can be good for Web applications (assuming you
              don't want to continue template processing after exception),
              because it gives the most control to the Web application over
              page generation on error conditions (since FreeMarker doesn't
              print anything to the output about the error). For more
              information about handling errors in Web applications <a href="app_faq.html#misc.faq.niceErrorPage">see the FAQ</a>.</p>
            </li>
          </ul>    </div>

        
            
  
  
  
  <h2 class="rank_section2"
        >
<a name="autoid_45"></a>Explicit error handling in templates  </h2>


          <p>Although it has nothing to do with the FreeMarker
          configuration (the topic of this chapter), for the sake of
          completeness it is mentioned here that you can handle errors
          directly in templates as well. This is usually a bad practice (try
          keep templates simple and non-technical), but nonetheless necessary
          sometimes:</p>

              <div class="itemizedlist">
<ul>
            <li>
              <p>Handling missing/null variables: <a href="dgui_template_exp.html#dgui_template_exp_missing">Template Author's Guide/The Template/Expressions/Handling missing values</a></p>
            </li>

            <li>
              <p>Surviving malfunctioning ``portlets'' and such expendable
              page sections: <a href="ref_directive_attempt.html">Reference/Directive Reference/attempt, recover</a></p>
            </li>
          </ul>    </div>

          
</div>

    <div class="navigation">
    <div class="pagers">
      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
<div class="pagerButton"><a href="pgui_misc.html"><span class="hideA">Next page: </span>Miscellaneous</a></div><div class="pagerButton"><a href="pgui_config_templateloading.html">Previous page</a></div><div class="pagerButton"><a href="pgui_config.html">Parent page</a></div><div class="pagerButton"><a href="index.html">Contents</a></div>      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
    </div>
    <div class="breadcrumb">
<span class="breadcrumb">        You are here:
          <a href="index.html">Book</a>
            <b>></b>
          <a href="pgui.html">Programmer's Guide</a>
            <b>></b>
          <a href="pgui_config.html">The Configuration</a>
            <b>></b>
          Error handling
</span>    </div>
    </div>

<table border=0 cellspacing=0 cellpadding=0 width="100%">
    <tr>
      <td colspan=2><img src="docgen-resources/img/none.gif" width=1 height=8 alt=""></td>
    <tr>
      <td align="left" valign="top"><span class="smallFooter">
            FreeMarker Manual -- For FreeMarker 2.3.16
            <br>
          HTML generated: 2009-12-08 08:38:54 GMT
      </span></td>
      <td align="right" valign="top"><span class="smallFooter">
          <a href="http://www.xmlmind.com/xmleditor/">
            <img src="docgen-resources/img/xxe.gif" alt="Edited with XMLMind XML Editor">
          </a>
      </span></td>
    </tr>
</table>
  <!-- Put pre-loaded images here: -->
  <div style="display: none">
    <img src="docgen-resources/img/linktargetmarker.gif" alt="Here!" />
  </div>
</body>
</html>

